Quick start

Also available in Spanish.

Install the needed tools

Download and install OpenXava (if not yet installed):

• Go to http://www.openxava.org/downloads
• Download the latest distribution. It's a zip file.
• Uncompress the file in your computer.

Download and install the JDK (if not yet installed):

• Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html
• Download the latest JDK. OpenXava works with Java 8, 7 and 6. (Don't use Java 9 or 10)
• Install it. Remember the path where you install the JDK, you'll need it to configure Tomcat in the next section.

Download and install Eclipse (if not yet installed):

• Go to http://www.eclipse.org/downloads/eclipse-packages
• Download 'Eclipse IDE for Java EE Developers'.
• Install it.

Configure Tomcat

You have to indicate Tomcat where you have installed the JDK.
With Windows, add the next line at the beginning of catalina.bat in tomcat\bin folder:

set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_45

Don't put C:\Program Files\Java\jdk1.8.0_45 put the real path where the JDK is installed in your system.
With Linux or Mac, add the next line at the beginning of catalina.sh in tomcat/bin folder:

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk

Don't put /usr/lib/jvm/java-8-openjdk put the real path where the JDK is installed in your system.

Start Tomcat

Start Tomcat, with Windows just double click on startup.bat of tomcat\bin:

If you use Linux or Mac run startup.sh located in the tomcat/bin folder of OpenXava:

Start Eclipse

Start Eclipse, it will ask you to choose the workspace, choose the one included in OpenXava:

If you already have Eclipse started use the option File >Switch Workspace. If you're using an old version of Eclipse it will ask you "Workspace ... was written with a newer version of the product and can be incompatible with this version. If you continue, this can cause unexpected behavior or data loss", don't worry, just click on OK.

Execute the example application

The OpenXava distribution comes with an example application called MySchool, in order to execute it follow the next steps.
Build and deploy the project:

Go to http://localhost:8080/MySchool/modules/Teacher using your browser to see the application in action:

Add another class

Add a new class to MySchool project:

Then type Pupil for the class name:

Copy the code below into your Pupil class:

package org.openxava.school.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
 
@Entity
public class Pupil {
 
    @Id @Column(length=2) @Required
    private int number;
 
    @Column(length=40) @Required
    private String name;
 
    public int getNumber() {
        return number;
    }
 
    public void setNumber(int number) {
        this.number = number;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
}

Now we can deploy it:

Go to http://localhost:8080/MySchool/modules/Pupil to see Pupil in action (if it asks for sign in, use user: admin, password: admin):

Add a teacher reference to pupil

It is easy to make a pupil to have a reference to a teacher. Add the next code to Pupil class :

public class Pupil {
 
    ...
 
    // BEGIN CODE TO ADD
    @ManyToOne
    private Teacher teacher;
 
    public Teacher getTeacher() {
        return teacher;
    }
 
    public void setTeacher(Teacher teacher) {
        this.teacher = teacher;
    }
    // END CODE TO ADD
 
}

Deploy it:

Go to http://localhost:8080/MySchool/modules/Pupil and select detail mode:

Show teacher reference as a combo

If you want the reference to be displayed in combo format, you should add @DescriptionsList to teacher reference in Pupil, as following:

public class Pupil {
 
    ...
 
    @DescriptionsList // ADD THIS
    @ManyToOne
    private Teacher teacher;
 
    ...
 
}

Now deploy again:

Go to http://localhost:8080/MySchool/modules/Pupil:

Add a collection of pupils to teacher

Let's put a pupils collection in teacher. Put the collection declaration inside the Teacher class:

public class Teacher {
 
    ...
 
    // BEGIN CODE TO ADD
    @OneToMany(mappedBy="teacher")
    private Collection<Pupil> pupils;
 
    public Collection <Pupil> getPupils() {
        return pupils;
    }
 
    public void setPupils(Collection <Pupil> pupils) {
        this.pupils = pupils;
    }
    // END CODE TO ADD
 
}

And deploy again:

Go to http://localhost:8080/MySchool/modules/Teacher:

Create your own project

Well done! You have executed and modified and already existing project. Now you should create your own OpenXava project from scratch:

Follow the lesson: Getting started

Any problem with this guide? Ask in the help forum.